home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / pcl / src-16f.lha / compiler / mips / random-doc.txt < prev    next >
Encoding:
Text File  |  1991-11-06  |  12.2 KB  |  352 lines
  1. -*- Mode: Text, Fill -*-
  2.  
  3. $Header: random-doc.txt,v 1.3 90/03/02 17:40:56 ch Exp $
  4.  
  5. DEFINE-STORAGE-BASE
  6.  
  7.   Define-Storage-Base Name Kind {Key Value}*
  8.  
  9.   Define a storage base having the specified Name.  Kind may be :Finite,
  10.   :Unbounded or :Non-Packed.  The following keywords are legal:
  11.  
  12.   :Size <Size>
  13.       Specify the number of locations in a :Finite SB or the initial size of a
  14.       :Unbounded SB.
  15.  
  16.  
  17. DEFINE-STORAGE-CLASS
  18.  
  19.   Define-Storage-Class Name Number Storage-Base {Key Value}*
  20.  
  21.   Define a storage class Name that uses the named Storage-Base.  Number is a
  22.   small, non-negative integer that is used as an alias.  The following
  23.   keywords are defined:
  24.  
  25.   :Element-Size <Size>
  26.       The size of objects in this SC in whatever units the SB uses.  This
  27.       defaults to 1.
  28.  
  29.   :Locations
  30.       If the SB is :Finite, then this is a list of the offsets within the SB
  31.       that are in this SC.
  32.  
  33.   
  34. DEFINE-MOVE-COSTS
  35.  
  36.   Define-Move-Costs {((Source-SC*) {(Cost Dest-SC*)}*)}*
  37.  
  38.   This macro declares the cost of the implicit move operations needed to load
  39.   arguments and store results.  The format is somewhat similar to the costs
  40.   specifications in Define-VOP.  Each argument form gives the cost for moving
  41.   to all possible destination SCs from some collection of equivalent source
  42.   SCs.
  43.  
  44.   This information is used only to compute the cost of moves from arguments to
  45.   Load TNs or from Load TNs to results.  It is not necessary to specify the
  46.   costs for moves between combinations of SCs impossible in this context.
  47.  
  48.  
  49. DEFINE-SAVE-SCS
  50.  
  51.   Define-Save-SCs {(save-sc saved-sc*)}*
  52.  
  53.   This form is used to define which SCs must be saved on a function call.  The
  54.   Saved-SCs are SCs that must be saved.  The Save-SC a SC that is used in
  55.   combination with the defined move costs to determine the cost of saving.
  56.  
  57.  
  58. DEF-PRIMITIVE-TYPE
  59.  
  60.   Def-Primitive-Type Name (SC*) {Key Value}*
  61.  
  62.   Define a primitive type Name.  Each SC specifies a Storage Class that values
  63.   of this type may be allocated in.  The following keyword options are defined:
  64.  
  65.   :Type
  66.       The type descriptor for the Lisp type that is equivalent to this type
  67.       (defaults to Name.)
  68.  
  69.  
  70. DEF-BOOLEAN-ATTRIBUTE
  71.  
  72.   Def-Boolean-Attribute Name Attribute-Name*
  73.  
  74.   Define a new class of boolean attributes, with the attributes havin the
  75.   specified Attribute-Names.  Name is the name of the class, which is used to
  76.   generate some macros to manipulate sets of the attributes: 
  77.  
  78.     NAME-attributep attributes attribute-name*
  79.       Return true if one of the named attributes is present, false otherwise.
  80.  
  81.     NAME-attributes attribute-name*
  82.       Return a set of the named attributes.
  83.  
  84.  
  85. PRIMITIVE-TYPE-VOP
  86.  
  87.   Primitive-Type-VOP Vop (Kind*) Type*
  88.  
  89.   Annotate all the specified primitive Types with the named VOP under each of
  90.   the specified kinds:
  91.  
  92.   :Coerce-To-T
  93.   :Coerce-From-T
  94.   :Move
  95.       One argument one result VOPs used for coercion between representations
  96.       and explicit moves.
  97.  
  98.   :Check
  99.       A one argument one result VOP that moves the argument to the result,
  100.       checking that the value is of this type in the process.
  101.  
  102. DEFINE-VOP
  103.  
  104.   Define-VOP (Name [Inherits]) Spec*
  105.  
  106.   Define the symbol Name to be a Virtual OPeration in the compiler.  If
  107.   specified, Inherits is the name of a VOP that we default unspecified
  108.   information from.  Each Spec is a list beginning with a keyword indicating
  109.   the interpretation of the other forms in the Spec:
  110.   
  111.   :Args {(Name {Key Value}*)}*
  112.   :Results {(Name {Key Value}*)}*
  113.       The Args and Results are specifications of the operand TNs passed to the
  114.       VOP.  The following operand options are defined:
  115.  
  116.       :SCs (SC*)
  117.       :Load T-or-NIL
  118.       :SCs specifies good SCs for this operand.  Other SCs will be
  119.       penalized according to move costs.  If :Load is true (the default),
  120.       then a load TN will be allocated if necessary, guaranteeing that the
  121.       operand is always one of the specified SCs.
  122.  
  123.       :More T-or-NIL
  124.       If specified, Name is bound to the TN-Ref for the first argument or
  125.       result following the fixed arguments or results.  A more operand must
  126.       appear last, and cannot be targeted or restricted.
  127.  
  128.       :Target Operand
  129.       This operand is targeted to the named operand, indicating a desire to
  130.       pack in the same location.  Not legal for results.
  131.   
  132.   :Conditional
  133.       This is used in place of :Results with conditional branch VOPs.  There
  134.       are no result values: the result is a transfer of control.  The
  135.       consequent and alternative continuations are passed as the first and
  136.       second :Info arguments.  A side-effect is to set the Predicate attribute
  137.       for functions in the :Translate option.
  138.   
  139.   :Temporary ({Key Value}*) Name*
  140.       Allocate a temporary TN for each Name, binding that variable to the TN
  141.       within the body of the generators.  In addition to :Target (which is 
  142.       is the same as for operands), the following options are
  143.       defined:
  144.  
  145.       :Type Type
  146.           Specify the primitive type for the temporary, default T.
  147.  
  148.       :SC SC-Name
  149.       :Offset SB-Offset
  150.       Force the temporary to be allocated in the specified SC with the
  151.       specified offset.  Offset is evaluated at macroexpand time.
  152.  
  153.       :SCs (SC*)
  154.       Restrict the temporary to a subset of the SCs allowed by the type,
  155.       possibly requiring packing in a finite SC.
  156.  
  157.       :From Time-Spec
  158.       :To Time-Spec
  159.       Specify the beginning and end of the temporary's lives.  The defaults
  160.       are :Load and :Save, i.e. the duration of the VOP.  The other
  161.       intervening phases are :Argument, :Eval and :Result.  Non-zero
  162.       sub-phases can be specified by a list, e.g. the second argument's
  163.       life ends at (:Argument 1).
  164.   
  165.   :Generator Cost Form*
  166.       Specifies the translation into assembly code. Cost is the estimated cost
  167.       of the code emitted by this generator. The body is arbitrary Lisp code
  168.       that emits the assembly language translation of the VOP.  An Assemble
  169.       form is wrapped around the body, so code may be emitted by using the
  170.       local Inst macro.  During the evaluation of the body, the names of the
  171.       operands and temporaries are bound to the actual TNs.
  172.   
  173.   :Effects Effect*
  174.   :Affected Effect*
  175.       Specifies the side effects that this VOP has and the side effects that
  176.       effect its execution.  If unspecified, these default to the worst case.
  177.   
  178.   :Info Name*
  179.       Define some magic arguments that are passed directly to the code
  180.       generator.  The corresponding trailing arguments to VOP or %Primitive are
  181.       stored in the VOP structure.  Within the body of the generators, the
  182.       named variables are bound to these values.  Except in the case of
  183.       :Conditional VOPs, :Info arguments cannot be specified for VOPS that are
  184.       the direct translation for a function (specified by :Translate).
  185.  
  186.   :Ignore Name*
  187.       Causes the named variables to be declared IGNORE in the generator body.
  188.  
  189.   :Variant Thing*
  190.   :Variant-Vars Name*
  191.       These options provide a way to parameterize families of VOPs that differ
  192.       only trivially.  :Variant makes the specified evaluated Things be the
  193.       "variant" associated with this VOP.  :Variant-Vars causes the named
  194.       variables to be bound to the corresponding Things within the body of the
  195.       generator.
  196.  
  197.   :Variant-Cost Cost
  198.       Specifies the cost of this VOP, overriding the cost of any inherited
  199.       generator.
  200.  
  201.   :Note String
  202.       A short noun-like phrase describing what this VOP "does", i.e. the
  203.       implementation strategy.  This is for use in efficiency notes.
  204.  
  205.   :Arg-Types Type*
  206.   :Result-Types Type*
  207.       Specify the template type restrictions used for automatic translation.
  208.       If there is a :More operand, the last type is the more type. 
  209.   
  210.   :Translate Name*
  211.       This option causes the VOP template to be entered as an IR2 translation
  212.       for the named functions.
  213.  
  214.   :Policy {:Small | :Fast | :Safe | :Fast-Safe}
  215.       Specifies the policy under which this VOP is the best translation.
  216.  
  217.   :Guard Form
  218.       Specifies a Form that is evaluated in the global environment.  If
  219.       form returns NIL, then emission of this VOP is prohibited even when
  220.       all other restrictions are met.
  221.  
  222.   :Save-P {T | NIL | :Force-To-Stack}
  223.       Indicates how a VOP wants live registers saved.
  224.  
  225.  
  226. SC-CASE
  227.  
  228.   SC-Case TN {({(SC-Name*) | SC-Name | T} Form*)}*
  229.  
  230.   Case off of TN's SC.  The first clause containing TN's SC is evaulated,
  231.   returning the values of the last form.  A clause beginning with T specifies a
  232.   default.  If it appears, it must be last.  If no default is specified, and no
  233.   clause matches, then an error is signalled.
  234.  
  235.  
  236. DEFINE-MISCOP
  237.  
  238.   Define-Miscop Name Args {Key Value}*
  239.  
  240.   Define a miscop with the specified args/results and options.  The
  241.   following keywords are defined:
  242.  
  243.   :results
  244.      Defaults to '(r).
  245.  
  246.   :translate
  247.   :policy
  248.   :arg-types
  249.   :result-types
  250.   :cost
  251.   :conditional
  252.  
  253.  
  254. DEFINE-MISCOP-VARIANTS
  255.  
  256.   Define-Miscop-Variants Vop Names*
  257.  
  258.   Define a bunch of miscops VOPs that inherit the specified VOP and whose
  259.   Template name, Miscop name and translate function are all the same.
  260.  
  261.  
  262. DEF-SOURCE-TRANSFORM
  263.  
  264.   Def-Source-Transform Name Lambda-List Form*
  265.  
  266.   Define a macro-like source-to-source transformation for the function Name.
  267.   A source transform may "pass" by returning a non-nil second value.  If the
  268.   transform passes, then the form is converted as a normal function call.  If
  269.   the supplied arguments are not compatible with the specified lambda-list,
  270.   then the transform automatically passes.
  271.   
  272.   Source-Transforms may only be defined for functions.  Source transformation
  273.   is not attempted if the function is declared Notinline.  Source transforms
  274.   should not examine their arguments.  If it matters how the function is used,
  275.   then Deftransform should be used to define an IR1 transformation.
  276.   
  277.   If the desirability of the transformation depends on the current Optimize
  278.   parameters, then the Policy macro should be used to determine when to pass.
  279.  
  280.  
  281. DEFKNOWN
  282.  
  283.   Defknown Name Arg-Types Result-Type [Attributes] {Key Value}* 
  284.  
  285.   Declare the function Name to be a known function.  We construct a type
  286.   specifier for the function by wrapping (FUNCTION ...) around the Arg-Types
  287.   and Result-Type.  Attributes is a an unevaluated list of the boolean
  288.   attributes that the function has.  These attributes are meaningful here:
  289.       call
  290.          May call functions that are passed as arguments.  In order to determine
  291.          what other effects are present, we must find the effects of all arguments
  292.          that may be functions.
  293.         
  294.       unsafe
  295.          May incorporate arguments in the result or somehow pass them upward.
  296.         
  297.       unwind
  298.          May fail to return during correct execution.  Errors are O.K.
  299.         
  300.       any
  301.          The (default) worst case.  Includes all the other bad things, plus any
  302.          other possible bad thing.
  303.         
  304.       foldable
  305.          May be constant-folded.  The function has no side effects, but may be
  306.          affected by side effects on the arguments.  e.g. SVREF, MAPC.
  307.         
  308.       flushable
  309.          May be eliminated if value is unused.  The function has no side effects
  310.          except possibly CONS.  If a function is defined to signal errors, then
  311.          it is not flushable even if it is movable or foldable.
  312.         
  313.       movable
  314.          May be moved with impunity.  Has no side effects except possibly CONS,
  315.          and is affected only by its arguments.
  316.  
  317.       predicate
  318.           A true predicate likely to be open-coded.  This is a hint to IR1
  319.       conversion that it should ensure calls always appear as an IF test.
  320.       Not usually specified to Defknown, since this is implementation
  321.       dependent, and is usually automatically set by the Define-VOP
  322.       :Conditional option.
  323.  
  324.   Name may also be a list of names, in which case the same information is given
  325.   to all the names.  The keywords specify the initial values for various
  326.   optimizers that the function might have.
  327.  
  328.  
  329. DEF-PRIMITIVE-TRANSLATOR
  330.  
  331.   Def-Primitive-Translator Name Lambda-List Form*
  332.  
  333.   Define a function that converts a use of (%PRIMITIVE Name ...) into Lisp
  334.   code.  Lambda-List is a defmacro style lambda list.
  335.  
  336.  
  337. CTYPE-OF
  338.  
  339.   CType-Of Object
  340.  
  341.   Like Type-Of, only returns a Type structure instead of a type
  342.   specifier.  We try to return the type most useful for type checking,
  343.   rather than trying to come up with the one that the user might find
  344.   most informative.
  345.  
  346.  
  347. SC-IS
  348.  
  349.   SC-Is TN SC*
  350.  
  351.   Returns true if TNs SC is any of the named SCs, false otherwise.
  352.